Skip to main content
Version: 2025.10

Jira Cloud

Summary​

The Jira Cloud integration enables extraction of comprehensive issue data from Atlassian Jira Cloud instances, including issue details, comments, history, transitions, and attachments.

Supported Versions: Jira Cloud

Connection Methods: Link (via Jira issue URL)

How and Where to Use​

You can use the Jira Cloud integration through either the Istari Digital Platform UI or the Istari Digital SDK. Both methods allow you to extract comprehensive data from Jira issues by providing a Jira issue URL or metadata link.

What You Can Do​

  • Extract complete issue data including fields, status, priority, assignee, reporter, and project information
  • Retrieve all comments associated with an issue
  • Access full issue history showing all changes over time
  • Extract issue transitions and workflow states
  • Download all attachments associated with an issue
  • Generate metadata reports for processing validation

Prerequisites​

Before using this integration, ensure:

  • You have access to a Jira Cloud instance
  • You have a valid Jira API token (see Atlassian documentation)
  • Your Jira account has permission to view the issues you want to extract
  • The Istari Digital Agent is installed and configured by your administrator
  • You have access to the Istari Digital Platform UI or the Istari Digital SDK

API​

Functions​

FunctionDescriptionInputsOutputs
@istari:extractExtracts comprehensive data from a Jira Cloud issueJira issue link (.istari_jira_metadata)Issue data (JSON), Comments (JSON), History (JSON), Transitions (JSON), Attachments (directory), Metadata report (JSON)

Output Examples​

Output NameTypeDescription
issue_dataJSON fileComplete issue data including fields, status, priority, assignee, reporter, project, description, and summary
commentsJSON fileAll comments on the issue with author, timestamp, and content
historyJSON fileComplete change history showing all modifications to the issue over time
transitionsJSON fileIssue workflow transitions and status changes
attachmentsDirectoryAll files attached to the issue (images, documents, etc.)
metadata_reportJSON fileProcessing metadata including extraction summary, counts, and status information

Usage​

Link to Jira issues directly by providing a Jira issue URL. The Istari Digital Platform will create the required metadata file automatically, or you can upload a manually created metadata file.

Using the Istari Digital Platform UI​

Follow these steps to extract Jira data using the web interface:

  1. Navigate to the Files page.
    Click the Files option in the left-hand sidebar.

  2. Link or upload your Jira issue.
    You have two options:

    • Option A: Paste a Jira issue URL (e.g., https://your-instance.atlassian.net/browse/PROJ-123) directly in the web interface. The platform will automatically create the required metadata file.
    • Option B: Create a metadata file manually (see below) with the extension .istari_jira_metadata and upload it.

  3. Open the linked issue.
    Click on the newly created Jira metadata file in your files list.

  4. Navigate to the Artifacts tab.
    Click the Artifacts tab to view and manage artifacts associated with this issue.

  5. Fill out the function execution form.
    In the Execute Function section, provide the following information:

    • Tool Name: jira
    • Version: Cloud
    • Operating System: Select the OS where your Istari Digital Agent is running (e.g., Windows 11, Ubuntu 22.04)
    • Function: @istari:extract
    • Agent: Select the appropriate agent from the dropdown

  6. Run the function.
    Click the Run or Execute button to start the extraction job.

  7. Monitor job progress.
    The page will display the job status. Wait for it to complete (this may take a few moments depending on issue size and number of attachments).

  8. View results.
    Once the job completes successfully, the extracted artifacts will appear in the Artifacts tab.

  9. Download or view artifacts.
    Click on any artifact to view its contents in the browser, or download artifacts for local analysis.

Creating a Metadata File Manually (Option B)​

If you prefer to create the metadata file yourself, create a JSON file with the following structure and save it with the .istari_jira_metadata extension:

{
  "link": "https://your-instance.atlassian.net/browse/PROJ-123"
}

Example File:

Then upload this file to the Istari Digital Platform as you would any other file.

Using the Istari Digital SDK​

Prerequisite: Install Istari Digital SDK and initialize Istari Digital Client per instructions here​

Step 1: Upload and Extract the File(s)​

Create and upload the metadata file as a model​

import json
from pathlib import Path

# Create the Jira metadata file
jira_metadata = {
    "link": "https://your-instance.atlassian.net/browse/PROJ-123"
}

# Save to a file with .istari_jira_metadata extension
metadata_path = Path("PROJ-123.istari_jira_metadata")
with open(metadata_path, "w") as f:
    json.dump(jira_metadata, f, indent=2)

# Upload the metadata file as a model
model = client.add_model(
    path=str(metadata_path),
    description="Jira issue PROJ-123",
    display_name="PROJ-123 Issue Data",
)
print(f"Uploaded Jira metadata with model ID {model.id}")

Extract once you have the model ID​

extraction_job = client.add_job(
    model_id=model.id,
    function="@istari:extract",
    tool_name="jira",
    tool_version="Cloud",
    operating_system="Windows 11",  # Or: Ubuntu 22.04, Windows 10, etc.
)
print(f"Extraction started for model ID {model.id}, job ID: {extraction_job.id}")

Step 2: Check the Job Status​

extraction_job.poll_job()

Step 3: Retrieve Results​

Example​

# Retrieve the model with updated artifacts
model = client.get_model(model.id)

for artifact in model.artifacts:
    output_file_path = f"c:\\jira_extracts\\{artifact.name}"

    # Create directory if needed
    Path(output_file_path).parent.mkdir(parents=True, exist_ok=True)

    if artifact.extension in ["txt", "csv", "md", "json", "html"]:
        with open(output_file_path, "w") as f:
            f.write(artifact.read_text())
        print(f"Saved text artifact: {output_file_path}")
    else:
        with open(output_file_path, "wb") as f:
            f.write(artifact.read_bytes())
        print(f"Saved binary artifact: {output_file_path}")

Notes on Output Files​

  • Issue Data (*_data.json): Contains the complete issue information including all fields, custom fields, status, priority, project details, and more.
  • Comments (*_comments.json): If the issue has comments, this file contains all comments with author information and timestamps.
  • History (*_history.json): Contains the complete change history showing all modifications made to the issue over time.
  • Transitions (*_transitions.json): Contains workflow transition information and status changes.
  • Attachments: If the issue has attachments, they will be saved to a directory. File types vary based on what was attached to the issue (images, PDFs, documents, etc.).
  • Metadata Report (*_metadata.json): Contains processing information, extraction summary, and validation data.

Installation​

Prerequisites​

  • Python 3.11 or higher (for development only)
  • Jira Cloud instance access
  • Jira API token (not Personal Access Token)
  • Istari Digital Agent version 9.0.0 or higher

Configuration​

Module Version 1.0.0+: Configuration Required

The Jira integration requires configuration to connect to your Jira Cloud instance. You must provide your Jira instance URL, email address, and API token.

Centralized Configuration​

The Istari Agent is configured via the file istari_digital_config.yaml. The Agent expects the file to be located at:

  • %LOCALAPPDATA%\istari_digital\ on Windows
  • ~/.config/istari_digital/ on RHEL/Ubuntu

Configure the Jira module using the istari_digital_agent_module_configurations section. The agent will pass this centralized configuration to the module:

agent:
  istari_digital_agent_module_configurations:
    "@istari:jira":
      "jira_instance_url": "https://your-instance.atlassian.net" # required
      "jira_email": "your-email@company.com" # required
      "jira_api_token": "your-api-token-here" # required
      "jira_log_level": "INFO" # optional
      "jira_log_file_path": "jira_module.log" # optional

Configuration Parameters​

ParameterTypeRequiredDescription
jira_instance_urlStringRequiredThe full URL of your Jira Cloud instance (e.g., https://your-company.atlassian.net)
jira_emailStringRequiredYour Jira account email address used for authentication
jira_api_tokenStringRequiredYour Jira API token. Generate one from your Atlassian account settings
jira_log_levelStringOptionalLogging level for the module. Options: DEBUG, INFO, WARNING, ERROR. Default: INFO
jira_log_file_pathStringOptionalPath to the log file for module execution. Default: jira_module.log

How to Get a Jira API Token​

  1. Log in to your Atlassian account at https://id.atlassian.com
  2. Navigate to Security → API tokens
  3. Click Create API token
  4. Give your token a descriptive label (e.g., "Istari Digital Integration")
  5. Copy the generated token immediately (you won't be able to see it again)
  6. Paste the token into your istari_digital_config.yaml configuration file
Keep Your API Token Secure

Treat your Jira API token like a password. Never commit it to version control or share it publicly. Store it securely in the configuration file with appropriate file permissions.

License Configuration​

No additional license configuration is required for the Jira Cloud integration. You only need:

  • Access to a Jira Cloud instance
  • A valid Jira account with appropriate permissions
  • A Jira API token for authentication

Versions​

Current Module Version: 1.0.0​

This is the initial release of the Jira Cloud integration module.

Compatibility Notes​

  • Agent Version: Requires Istari Digital Agent version 9.0.0 or higher
  • Jira Version: Supports Jira Cloud only (not Jira Server or Jira Data Center at this time)
  • Operating Systems: Windows 10, Windows 11, Ubuntu 22.04
  • Python Version: 3.11+ (development dependency only; end users don't need Python)
  • API Version: Uses Jira REST API v3

Changelog​

Module Version 1.0.0​

Release Date: December 2024

Initial Release Features:

  • Extract comprehensive issue data from Jira Cloud
  • Retrieve issue comments with full content and metadata
  • Access complete issue change history
  • Extract workflow transitions and status changes
  • Download all issue attachments
  • Generate processing metadata reports
  • Support for Jira Cloud REST API v3
  • Configurable logging levels
  • Error handling with detailed error reporting

Release Notes​

Key Changes Between Versions​

Version 1.0.0 (Initial Release):

  • First public release of the Jira Cloud integration
  • Provides extraction capabilities for Jira Cloud issues
  • Supports Windows 10, Windows 11, and Ubuntu 22.04
  • Requires Istari Digital Agent 9.0.0 or higher

Troubleshooting​

Common Issues​

Issue: Authentication Failed

  • Symptom: Error messages indicating "401 Unauthorized" or "Authentication failed"
  • Cause: Invalid API token, incorrect email address, or expired token
  • Solution:
    1. Verify your jira_email matches your Atlassian account email exactly
    2. Generate a new API token from Atlassian account settings
    3. Update your istari_digital_config.yaml with the new token
    4. Ensure there are no extra spaces or characters in your configuration
    5. Restart the Istari Digital Agent after updating the configuration

Issue: Cannot Find Issue

  • Symptom: Error messages indicating "Issue not found" or "404 Not Found"
  • Cause: Issue key is incorrect, issue doesn't exist, or you don't have permission to view the issue
  • Solution:
    1. Verify the issue key or URL is correct (e.g., PROJ-123)
    2. Check that you can view the issue by logging into Jira Cloud with the same account
    3. Ensure your Jira account has permission to view the project and issue
    4. Confirm the issue hasn't been deleted or moved to a different project

Issue: Connection to Jira Instance Failed

  • Symptom: Error messages indicating connection timeout or "Cannot connect to Jira instance"
  • Cause: Incorrect instance URL, network issues, or firewall blocking the connection
  • Solution:
    1. Verify your jira_instance_url is correct (e.g., https://your-company.atlassian.net)
    2. Ensure the URL does not have a trailing slash
    3. Check network connectivity from the machine running the Istari Digital Agent
    4. Verify firewall rules allow outbound HTTPS connections to *.atlassian.net
    5. Test by accessing the Jira instance URL in a web browser from the same machine

Issue: Missing Attachments in Output

  • Symptom: Attachments directory is empty or missing expected files
  • Cause: Attachment download failed, insufficient permissions, or no attachments exist on the issue
  • Solution:
    1. Verify the issue actually has attachments by viewing it in Jira Cloud
    2. Check that your Jira account has permission to view attachments
    3. Review the metadata_report artifact for information about download status
    4. Check the module logs for specific error messages about attachment downloads
    5. Ensure sufficient disk space is available on the agent machine

Issue: Module Not Found or Won't Execute

  • Symptom: Error messages indicating the module cannot be found or executed
  • Cause: Module not installed correctly, wrong agent version, or configuration issues
  • Solution:
    1. Verify Istari Digital Agent version is 9.0.0 or higher
    2. Check that the Jira module is installed in the correct agent modules directory
    3. Restart the Istari Digital Agent service
    4. Review agent logs for specific error messages
    5. Contact your administrator to verify the module installation

Getting Help​

If you continue to experience issues:

  1. Check the module log file (default: jira_module.log) for detailed error messages
  2. Review the Istari Digital Agent logs for additional context
  3. Consult the main troubleshooting guide for general agent and connectivity issues
  4. Contact Istari Digital support with:
    • Module version (1.0.0)
    • Agent version
    • Operating system
    • Error messages from logs
    • Steps to reproduce the issue

Tips and Best Practices​

Optimal Usage Patterns​

  • Batch Processing: If you need to extract data from multiple issues, create separate metadata files for each issue and process them as a batch to optimize workflow efficiency.
  • Regular Extractions: For issues that change frequently, schedule regular extractions to maintain up-to-date data in your Istari Digital Platform.
  • Attachment Management: Be aware that issues with many or large attachments will take longer to process. Monitor disk space on the agent machine.

Performance Considerations​

  • Network Latency: Extraction speed depends on network connectivity to Jira Cloud. Ensure stable, high-bandwidth connections for optimal performance.
  • Issue Complexity: Issues with extensive history, many comments, or numerous attachments will take longer to extract.
  • API Rate Limits: Jira Cloud has API rate limits. If processing many issues rapidly, you may encounter rate limiting. Space out batch operations if needed.

Security Best Practices​

  • API Token Rotation: Regularly rotate your Jira API tokens (e.g., every 90 days) for enhanced security.
  • Least Privilege: Use a Jira account with minimal necessary permissions for extraction. Avoid using administrator accounts.
  • Configuration Security: Ensure the istari_digital_config.yaml file has appropriate file permissions (readable only by the agent service account).
  • Audit Trail: Enable Jira audit logging to track API access and data extraction activities.

Data Management​

  • Metadata Reports: Always review the metadata_report artifact after extraction to validate successful processing and identify any issues.
  • Organized Storage: Use descriptive model names and organize extracted data by project or issue type for easier retrieval.
  • Archival: Consider archiving older issue extractions to free up space while maintaining historical records.

FAQ​

  • Is Jira Server or Jira Data Center supported?

    • Currently, only Jira Cloud is supported. Support for Jira Server and Jira Data Center may be added in future releases.

  • Can I extract data from private/restricted issues?

    • Yes, as long as the Jira account used for authentication has permission to view those issues. The integration respects all Jira permission schemes.

  • What happens if an issue is updated after I extract it?

    • The extraction creates a snapshot of the issue at the time of extraction. To get updated data, run the extraction function again on the same issue.

  • Why do I need an API token instead of my password?

    • API tokens are more secure than passwords. They can be easily revoked without changing your password, have limited scope, and are the recommended authentication method for API integrations by Atlassian.

  • Can I extract data from multiple Jira instances?

    • Yes, but you need to configure each instance separately in your istari_digital_config.yaml or use different agents for different instances. Each extraction job targets one specific Jira instance based on the configuration.

  • How long are API tokens valid?

    • Jira API tokens do not expire automatically, but Atlassian recommends rotating them regularly for security. You can revoke and create new tokens at any time from your Atlassian account settings.

  • What if my Jira instance uses custom fields?

    • Custom fields are fully supported. They will appear in the extracted issue_data JSON with their field IDs and values, just like standard Jira fields.

  • Can I automate the extraction process?

    • Yes! Use the Istari Digital SDK to script automated extractions. You can create workflows that regularly extract issue data, process it, and integrate it with other tools in your digital thread.